<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>Running Ibator</title>
  <link type="text/css" rel="stylesheet" href="ibator.css"/>
</head>
<body>

<div class="menuNav">
  <p>
    <a href="index.html" target="_top">Show Menu</a>
    <a href="running.html" target="_top">Hide Menu</a>
  </p>
</div>

<h1>Running Ibator</h1>
<p>Ibator can be run in the following ways:</p>
<ul>
  <li>From the command line with an XML configuration</li>
  <li>As an Ant task with an XML configuration</li>
  <li>From another Java program with an XML configuration</li>
  <li>From another Java program with a Java based configuration</li>
</ul>
<p>Each method is described in detail below.</p>
<p><b>Note:</b> there is also an Eclipse
plugin for Ibator that adds extra function - namely good integration into Eclipse,
an Eclipse enabled Ant task, and support for automatic merging of
Java files.  See the
<a target="_blank" href="http://ibatis.apache.org/ibator.html">Ibator</a>
home page for information on installing the Eclipse plugin.</p>

<p><b>Important:</b> When running outside of an IDE environment like Eclipse,
  Ibator interprets the <code>targetProject</code> and
  <code>targetPackage</code> attributes in all XML configurations as follows:</p>
<ul>
  <li><code>targetProject</code> is assumed to be an existing directory structure.
    Ibator will fail if this directory structure does not exist.</li>
   <li><code>targetPackage</code> will be translated to a suitable subdirectory
     structure of the <code>targetProject</code>
     directory structure.  Ibator will create these subdirectories if necessary.</li>
</ul>

<h2>Running Ibator from the Command Line</h2>
<p>Ibator may be run directly from the command line.  The JAR manifest includes the
   name of the default class (<code>org.apache.ibatis.ibator.api.IbatorRunner</code>)
   or you may specify it yourself.  The <code>IbatorRunner</code>
   class accepts several arguments as detailed below:</p>
<table border="1" cellspacing="0" cellpadding="5">
<tr>
  <th>Argument</th>
  <th>Value</th>
</tr>
<tr>
  <td>-configfile (required)</td>
  <td>Specifies the name of the configuration file.</td>
</tr>
<tr>
  <td>-overwrite (optional)</td>
  <td>If specified, then existing Java files will be overwritten if an existing Java
      file if found with the same nae as a generated file.  If not specified, and a
      Java file already exists with the same name as a generated file, then Ibator
      will write the newly generated Java file to the proper directory with a
      unique name (e.g. MyClass.java.1, MyClass.java.2, etc.).
      <b>Important: Ibator will always merge and overwrite XML files.</b></td>
</tr>
<tr>
  <td>-contextids (optional)</td>
  <td>If specified, then this is a comma delimited list of contexts to use in
      the current run of Ibator.  Any id specified in the list must exactly
      match the value of the <code>id</code> attribute of an
      &lt;ibatorContext&gt; configuration element.  Only ids specified
      in this list will be active for this run of Ibator.  If this argument
      is not specified, then all contexts will be active.</td>
</tr>
<tr>
  <td>-tables (optional)</td>
  <td>If specified, then this is a comma delimited list of tables to use in
      the current run of Ibator.  Any table specified in the list must exactly
      match the fully qualified table name specified in a
      &lt;table&gt; configuration element.  Only tables specified
      in this list will be active for this run of Ibator.  If this argument
      is not specified, then all tables will be active.
      Specify table names as: <br/><br/>
      <code>table</code><br/>
      <code>schema.table</code><br/>
      <code>catalog..table</code><br/>
      etc.</td>
</tr>
</table>

<p>You must create an Ibator XML configuration file to run Ibator from the
   command line.  If the file is
   named "ibatorConfig.xml", then any of the following command lines will run
   Ibator:</p>
<pre>
   java -jar ibator.jar -configfile ibatorConfig.xml
   java -jar ibator.jar -configfile ibatorConfig.xml -overwrite
   java -cp ibator.jar org.apache.ibatis.ibator.api.IbatorRunner -configfile ibatorConfig.xml
   java -cp ibator.jar org.apache.ibatis.ibator.api.IbatorRunner -configfile ibatorConfig.xml -overwrite
</pre>

<h2>Running Ibator from Ant</h2>
<p>Ibator includes a simple Ant task.  The task must be defined in your
  build.xml file, and the task has three parameters.  Here is an example
  build.xml file:</p>
<pre>
   &lt;project default="genfiles" basedir="."&gt;
     &lt;property name="generated.source.dir" value="${basedir}" /&gt;

     &lt;target name="genfiles" description="Generate the files"&gt;
       &lt;taskdef name="ibator"
                classname="org.apache.ibatis.ibator.ant.IbatorAntTask"
                classpath="ibator.jar" /&gt;
       &lt;ibator overwrite="true" configfile="ibatorConfig.xml" verbose="false" &gt;
         &lt;propertyset&gt;
           &lt;propertyref name="generated.source.dir"/&gt;
         &lt;/propertyset&gt;
       &lt;/ibator&gt;
     &lt;/target&gt;
   &lt;/project&gt;
</pre>

<p>Ibator task attributes are as follows:</p>
<table border="1" cellspacing="0" cellpadding="5">
<tr>
  <th>Attribute</th>
  <th>Value</th>
</tr>
<tr>
  <td>configfile (required)</td>
  <td>Specifies the name of the configuration file.</td>
</tr>
<tr>
  <td>overwrite (optional)</td>
  <td>If "true", "yes", etc., then existing Java files will be overwritten if an existing Java
      file if found with the same nae as a generated file.  If "false", "no", etc., and a
      Java file already exists with the same name as a generated file, then Ibator
      will write the newly generated Java file to the proper directory with a
      unique name (e.g. MyClass.java.1, MyClass.java.2, etc.).
      <b>Important: Ibator will always merge and overwrite XML files.</b></td>
</tr>
<tr>
  <td>contextids (optional)</td>
  <td>If specified, then this is a comma delimited list of contexts to use in
      the current run of Ibator.  Any id specified in the list must exactly
      match the value of the <code>id</code> attribute of an
      &lt;ibatorContext&gt; configuration element.  Only ids specified
      in this list will be active for this run of Ibator.  If this argument
      is not specified, then all contexts will be active.</td>
</tr>
<tr>
  <td>tables (optional)</td>
  <td>If specified, then this is a comma delimited list of tables to use in
      the current run of Ibator.  Any table specified in the list must exactly
      match the fully qualified table name specified in a
      &lt;table&gt; configuration element.  Only tables specified
      in this list will be active for this run of Ibator.  If this argument
      is not specified, then all tables will be active.
      Specify table names as: <br/><br/>
      <code>table</code><br/>
      <code>schema.table</code><br/>
      <code>catalog..table</code><br/>
      etc.</td>
</tr>
<tr>
  <td>verbose (optional)</td>
  <td>If "true", "yes", etc., then Ibator will log progress messages to the
      ant console (if Ant is running in verbose mode).  The default is "false".</td>
</tr>
</table>

<p>Notes:</p>
<ul>
  <li>The classpath on the &lt;taskdef&gt; is used to tell Ant where the Ibator JAR file
     is.  This is optional if you add Ibator to the Ant classpath in one
     of the other ways described in the Ant manual</li>
   <li>The name of the task can be anything you desire, "ibator" is
     simply an example</li>
   <li>The task supports an optional nested <code>&lt;propertyset&gt;</code> element which
       is the standard Ant property set type.  This can be used to pass parameters into
       a configuration file.  For example, the above property
       <code>generated.source.dir</code> can be
       accessed in the Ibator configuration file with the escape sequence
       <code>${generated.source.dir}</code>
   </li>
   <li>If a property is specified in the configuration file and is not resolved,
       then the escaped property string will be passed "as is" into the generated code.
   </li>
</ul>

<h2>Running Ibator from Java with an XML Configuration File</h2>
<p>The following code sample shows how to call Ibator from Java.  It does not
   show exception handling, but that should be obvious from the compiler
   errors :)</p>
<pre>
   List&lt;String&gt; warnings = new ArrayList&lt;String&gt;();
   boolean overwrite = true;
   File configFile = new File("ibatorConfig.xml");
   IbatorConfigurationParser cp = new IbatorConfigurationParser(warnings);
   IbatorConfiguration config = cp.parseIbatorConfiguration(configFile);
   DefaultShellCallback callback = new DefaultShellCallback(overwrite);
   Ibator ibator = new Ibator(config, callback, warnings);
   ibator.generate(null);
</pre>

<p>Notes:</p>
<ul>
   <li>Configuration file properties may be passed to the parser as a parameter on
       the IbatorConfigurationParser constructor.  If not passed explicitly, the JVM
       system properties will be searched for the value of configuration file
       properties.  For example, the property
       <code>generated.source.dir</code> can be
       accessed in the Ibator configuration file with the escape sequence
       <code>${generated.source.dir}</code>
   </li>
   <li>If a property is specified in the configuration file and is not resolved,
       then the escaped property string will be passed "as is" into the generated code.
   </li>
</ul>

<h2>Running Ibator from Java with a Java Based Configuration</h2>
<p>The following code sample shows how to call Ibator from Java only.  It does
   not show exception handling, but that should be obvious from the compiler
   errors :)</p>
<pre>
   List&lt;String&gt; warnings = new ArrayList&lt;String&gt;();
   boolean overwrite = true;
   IbatorConfiguration config = new IbatorConfiguration();

   //   ... fill out the config object as appropriate...

   DefaultShellCallback callback = new DefaultShellCallback(overwrite);
   Ibator ibator = new Ibator(config, callback, warnings);
   ibator.generate(null);
</pre>

</body>
</html>